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1 INTRODUCTION 
VMSINSTAL is a procedure which parece the installation of software 


roducts on an existing VAX/VMS system. It is used to install both 
S products (updates and meresees ay optional software products. 

compietely subsumes the functionality of VMSUPDATE and the current 
VMSINSTAL. Our current plans are to remove VMSUPDATE and the old 
VMSINSTAL in a future major release. 


This document describes the features of VMS V4.0 VMSINSTAL, and Lays 
out a set of guidelines for layered products to use when designing 
their installation procedures. Therefore, some of the features 
described herein do not apply to the VMS v3.x yorstene of VMSINSTAL. 
The use of VMSINSTAL and adherence to the guidelines will accomplish 
the following goals. 


© Product kits are composed of BACKUP savesets, which allow 
files larger than a single console volume to be included in 
the kit. urthermore, BACKUP can recover from media errors 
in some cases. 


o Products may be installed from a wide variety of media, 
including console media, tapes, disks, and the network. 


o Multiple products can be included on the same distribution 
volume. This is useful for software specialists and may 
become a distribution scheme in the future. 


o Consistency among software product installations will be 
increased. 


o Software product installation procedures should be more 
mmune to changes in VMS from one version to the next. 


1.1 Software Product Conventions 


In order to produce a software product that can be smoothly integrated 
nto the S environment, and that can coexist with other products, 
you must follow certain conventions when designing and building the 
product. These conventions are described in detail in various 

uments available from the Spit Brook SQM group. ALl such documents 
can be obtained by logging into the VASINFO account on AURORA 
(passwo:d VMSINFO). 
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1.2 Identifying Products 
Each VAX software proguct is identified by a facilit code. This is a 
ers. acilit 


e of up to six alphameric charac The code must 
be registered with the 


qpneres VMS rome’ registrar, who can be 
L to AURORA: :Facility_Registrar. 


As versions and — are released, they are gee toned unique 
version/update numbers. These are -digit integers in the form vvu, 
where vv is the major version number and u is the update. for 
greneie. VMS V5.0 receives the number 030, while the first update will 


1.3 A Quick User's Guide 


The proves manager installs software products by Logging into the 
SYSTEM account and invoking VMSINSTAL. No other commands are required 
ee, poteniten the environment. The VMSINSTAL procedure is invoked as 
ollows: 


$ @SYSSUPDATE:VMSINSTAL Cproduct,...J] Cdevice] 
The first parameter specifies the preswstte: that the user wishes to 
install. VMSINSTAL prompts if this parameter is omitted. A product 
can have one of three forms. 


o facvvu = The particular version/update of the specified 
product is installed. 


o fac - All versions and updates of the specified product are 
installed in order. 


* = Every product on the distribution volume is installed by 
installing all versions and updates in order. 
Products are installed in alphabetical order. 
The second parameter identifies the device where the distribution 
waynen are to be mounted. VMSINSTAL prompts if this parameter is 
om ‘ 


The precesure also accepts various options which are described in 
Chapter 5. 
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2 PACKAGING SOFTWARE PRODUCTS 


A VMS software product is distributed to the customer in a form called 
a ‘kit’. A kit consists of one or more BACKUP savesets, each with a 
standardized name. VMSINSTAL allows these savesets to reside on any 
disk or tape media, including, of course, the console media. Eac 
saveset is named as follows: 


facvvu.s where fac is the te Be code 
vv is the major version number 
u_-—s is: the update number 
5 is a sequence ‘etter 


The pees itty code and version/update number have ee | been 
described. The sequence letter provides for 26 savesets per kit. The 
following paragraphs describe the kits in greater detail. 


o Floppy - Each volume Label for a floppy kit should be in the 
format facnn, where fac is the facility code and nn is a 
sequence number. The kit must be created directly on the 
master distribution volumes using BACKUP to create sequential 
disk savesets. The a es | qualifiers are required: 
/INTERCHANGE, /VERIFY, /BLOCK_SIZE=9000, /GROUP_SIZE=25. The 
latter two result in optimal use of the blocks on the 
floppies. Don't forget to initialize double-density floppies 
for single-density use, or the SDC will have problems. 


o TUS8 = Just Like floppies. 


o Magnetic Tape - The aagnethe tape volume label should be in 
the format fac, where fac is the facility code. The kit must 
be created directly on the master volume using BACKUP to 
create savesets. The following qualifiers are required: 
/INTERCHANGE, /VERIFY. The savesets must be placed on the 
tape inorder. If desired, any number of kits may be placed 
on one magnetic tape. 


o Files-11 Disk - A kit may be created Sirectty into an 
arbitrary directory of a fFiles-11 disk. This is not 
currently a distribution method, but may become one in the 
future. The pes toying qualifiers are required: 
/INTERCHANGE, /VERIFY. If desired, any number of kits may be 
placed in a directory. 


The conventions described for volume labels are strong suggestions, 
although VMSINSTAL requires no particular labelling scheme. The owner 
UIC of files in the savesets is irrelevent. The protection of files 
must be as specified in section 3.3.1. 
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2.1 The SPKITBLD Procedure 


The rather erase fules escribed above are embodied in a DCL pr pecurs 
named SPKIT OM. This fregee edure may be used to build your K rs, 8 
you may steal code from your own procedures. est 
ee of SPKITBLD will be kept n the same public + - a4 5 
cumen 


SPKITBLD is invoked as follows: 
$ @SPKITBLD Cfacvvu) Cdevice) Ca-files) 


The ee parameter is the name of the kit to be built. VMSINSTAL 
prompts if this parameter is omitted. 


The second parameter is the device on which the kit is to be built. 
If J. Rey to build the kit in a Files-11 1 firestory. then the 
porepe an include a § directory specification. Volume 
nittal ization is performed when appropriate. tas insta prompts if 
this parameter is omitted. 


The ta parameter is a List of specifications of the files to be 
placed in the primary kit saveset A. Stickiness prevails and 
= Se are allowed. VMSINSTAL prompts if this parameter is 
omitted. 


SPKITBLD always prompts for information about additional savesets. 
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3 THE INSTALLATION PROCEDURE 


The VMSINSTAL procedure, a bundled and supported VMS Fog et tty 
provides the logic to install software products on an exist ng vag 
fee a It accomplishes this installation by interacting in a 
standardized fashion with the software product kit. This interaction 
falls into three major categories. 


1. VMSINSTAL agence that the kit has been created as described 
in Chapter 2. 


2. VMSINSTAL assumes that the principal saveset is the one with 
sequence letter A. This saveset must begin on volume 1 of 
the kit, and it must contain a DCL procedure named 

KITINSTAL.COM. 


3. KITINSTAL.COM drives the installation of the product by 
requesting services from VMSINSTAL. These services are 
requested by recursively sesh VMSINSTAL with the 

appro rete, parameters. Hence they are referred to as 

callbacks”. 


3.1 Overview Of VMSINSTAL Logic 
VMSINSTAL performs the following steps when invoked. 
1. Initialize and set up the standard environment. 


2. Prompt for the device parameter if not supplied by the user, 
and verify this parameter. 


3. Ask the user which products are to be installed from the next 
distribution volume set. Also allow the user to exit. Mount 
dd | volume of the set and make a List of products to be 

nstalled. 


4. Establish the final file environment for the installation. 
This includes the use of tailoring to create the maximum free 
space on the system disk (if this is a small disk system). 


5. Prepare to install the next product on the List. If there 
are no more products, go back to step 3. 


6. Set up the environment necessary to install the product. 
This includes the creation of a working directory for the 
kit's installation procedure. 


KS 


~ 


-» Restore all of saveset A into the kit's working directory. 


- Invoke the KITINSTAL procedure restored from saveset A. The 
rocedure will utilize callbacks to ottect the installation. 
ome callbacks may not be performed immediately, but deferred 

until after the procedure has completed. 


9. Performs all callbacks which were deferred in step 8. 


10. Invoke the product's Installation Verification Procedure 
(IVP) if available. 


11. Clean up and delete the kit's working directory. Loop back 
to step 5 tor the next product. 


12. This is a special step that is -_ performed if the system 
crashed during an installation. It is invoked directly from 
coon soar to clean up after the crash. See Appendix for 
more detail. 


13. This is a special step that is performed when copying kit 
savesets into a disk directory for later installation. See 
Chapter 5 for more detail. 


The following sections expand upon the above information. 


3.2 The Kit's Installation Procedure 


The pecaere installation procedure for a software product is named 
KITINSTAL.COM. Subprocedures may also be supplied if needed. The 
prsaere procedure must qeeeee a romiert code as its first parameter. 

hen the procedure is invoked by VMSINSTAL to install the product, it 
does so in the following manner. 


$ Q@KITINSTAL VMIS_INSTALL kit-debug 


Therefore, every kit's procedure must handle the request code 
VMIS_INSTALL, which means to perform an installation of the product. 
The request code is also used under other circumstances, as described 


no 
throughout this document. The procedure must not yi tosty perform a 
GOTO to the request code, treating it as a label. This is because we 
may add request codes in the fu ure, which will cause an error. The 
procedure must check for specific requests and ignore all others. 


The a) a | parameter is a boolean value which specifies whether or 
not the ki — oettes was requested when VMSINSTAL was invoked. 


Please see Chapter or more detail. 


The installation procedure must exit back to VMSINSTAL with status 
If the installation was successful, exit with the status VMIS$_SUCCESS 
If it failed in an unrecoverable way, exit with VMIS_FAILURE.” If a 
unknown request code is received, exit with VMIS_UNSOPPORTED. 


3.3 The Installation Environment 


When VMSINSTAL executes the kit's installation procedure, it provides 
a strictly-defined environment in which the procedure must operate. 


3.3.1 Defaults 


When the kit's installation orocedure is invoked, the following 
process defaults will be in effect. The procedure must not change the 
defaults except via callbacks. 


o ALL components of the message prefix will be displayed. 
o ALL privileges will be enabled, except for BYPASS. 
o The UIC will be (1,4). 
rs) 


The default file protection will be system:RWED, owner:RWED, 
roup:RWED, world:RE. This may be changed in the future. 
te that files restored from a product saveset will keep 
their original protection, which should be the same as the 
default. The process default only pertains to files created 
during the installation. 


o The default device and directory will be MISSING:CMISSING); 
therefore all file references must be explicit. 


3.3.2 Naming Conventions 


Any ogicat names or giobel symbols which VMSINSTAL defines will begin 
with the prefix VMIS. If the kit's procedure needs logical names or 
giobal symbols, their names must begin with the facility code and a 
ollar sign (e.g., FORTS). The kit's procedure may define local 
symbols with any name. 


The kit's procedure should be very careful to avoid abbreviations in 
() 


n 
DCL commands. Verbs must not be abbreviated because special symbols 
may be defined for them by VMSINSTAL. Qualifiers should also be 
apetiee out, but abbreviation to four letters or more is allowed if 
absolutely necessary. 
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If the kit needs installation pubere edures, they may be ess toned any 
name. Any number of additional levels of procedure invocation are 
allowed (up to the Limits of DCL), but callbacks may only be performed 
from KITINSTAL.COM and its direct callees. 


3.3.3 Logical Names 


The following logical names are defined when the kit's procedure is 
invoked. 


Oo VMISKWD - The kit's ere directory created by VMSINSTAL. 
ALL references to the working directory must be made via this 
logical name. 


© VMISROOT = The top-level system directory for the target 


system on which the product is to be installed. All 
references to system directories must be of the for 

references to system directories must be of the § form 
VMISROOT:CSYSxxx]. You cannot use the SYS$ logical names 

VMISROOT:CSYSxxxJ. You cannot use the SYS$ logical names, 
nor can you refer directly to the system device 

nor can you refer directly to the system device. 


© VMISSPECIFIC = The system-specific top-level system directory 
for the target system on which the product is to be 
installed. In those cases where no common apetee directory 
structure is in use, VMISSPECIFIC will be identical to 
VMISROOT. If a common system directory exists, VMISSPECIFIC 
will still point to the system-specific top-level system 
eteectery while VMISROOT will point to the common top-level 
system directory. 


3.3.4 Global Symbols 
The following global symbols are defined when the kit's procedure is 
nvoked. 


Oo TRUE and FALSE - Symbolic constants which can be used to 
assign boolean values to symbols. 


© VMISALTERNATE_ROOT = A boolean symbol which specifies whether 
or not the product is being installed to an alternate root. 
You should try to write an installation procedure which 
doesn't need to know. 


Oo VMISCALLBACK = This is the symbol that is used to perform 
callbacks to VMSINSIAL. 


Pi 
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VMISCOMMON_ROOT = A boolean symbol which specifies whether or 
not the product is being installed to a common system root. 


VMISCONSOLE = A boolean symbol which specifies whether or not 
the distribution device is a console device. 


VMISDEVICE = The distribution device as an ASCII string. 


VMI$_FAILURE = The failure status returned 7 callbacks and 
by the kit's procedure. It has a severity of warning. 


VMISPLACE = The location of the distribution volume as an 
ASCII string. 


VMISPRODUCT = The product identification in the standard 
format facvvu. 


VMISREMOTE = A boolean —— which specifies whether or not 
the distribution volume is on a remote node. 


VMI$_SUCCESS = The success status returned by callbacks and 
by the kit's procedure. 


VMIS_UNSUPPORTED = The status returned by the kit's 
0: tate procedure if it is passed an unknown request 
code. 


pated opi | at - The version of VMS which is currently 
running. f a released version, this string will have the 
form “RELEASED, vvu'’. If a update field test version, this 
eerie will have the form "UPDATE FT,vvu'’. finality. if an 
upgre e field test baselevel, this string will have the form 
GRADE FT,xxxx’’, where xxxx is the full baselevel 
identification (not et ag pe four characters). You cannot 
tell from the baselevel identification which version is being 
field tested. (See the appendices for examples on how to 
decode VMISVMS_VERSION.) 


3.4 Additional Conventions 


This section describes some additional conventions that the kit's 
installation procedure must follow. these are miscellaneous 
conventions and are described in no particular order. 


— 
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3.4.1 Error Handling 


The kit's installation procedures must have an ON WARNING statement to 
handle errors. These errors may occur in the t's preeegervs 
themselves, or they oe be returned by a callback (VMIS_FAILURE is a 
warning status). In the best of all possible worlds, Ehis ON WARNING 
statement can just exit, propagating the status up a level: 


$ ON WARNING THEN EXIT S$STATUS 


If the procedure must do some cleanup, however, then the error 
handling might look as follows: 


% ON WARNING THEN GOTO ERROR 

SERROR: 

$ S = $STATUS 

$ Clean up. You must close any files you opened. 
$ Make sure to handle any errors that occur in the 
$ clean up. 

$ EXIT S$ 


3.4.2 Asking Questions 

Ask all questions of the user at the beginning of the installation 
procedure, so that afterwards the user can go out for a quickie. If 
the installation is being done from a fast device, such as a real disk 


or tape, the user won't have to wait around during the entire 
installation. 


3.4.3 SET Command 
Use of the SET command is Limited to the following cases. 
o SET VERIFY if in kit debug mode. 
o SET ON and SET NOON 
o SET FILE to alter files in the kit's working directory only. 


3.4.4 SHOW Command 


The kit's installation procedures must never vely on the format of 
output from the SkOW command, or any other utility. 


3.4.5 Compatibility Mode 


The kit's installation pl + ta must not make use of compat 
mode under the assumption that it is bundled with VMS. Compat 
mode may be unbundled in the future. 


ete 


3.4.6 Referencing Other Products 


Installation procedures may reference and invoke other optional 
software products. There are essentially four levels of such 
referencing. 


1. The procedures do not need to reference any other optional 
products. 


2. The procedures need to alter their flow based upon the 
existence of another product, but do not reference the 
product. Use the FIND_FILE callback to determine tne 
existence of the product. 


3. The procedures need to reference another product's files, but 
do not invoke the product. Use the FIND_FILE callback to 
determine the existence of the product and set up a logical 
name to reference a file. 


4. The procedures need to invoke another product. Use the 
FIND FILE callback to determine the existence of the product. 
Invoke the product in the standard fashion. NOTE that the 
invocation of another product probably involves implicit 
references to the other product's files. VMSINSTAL assumes 
these files are in the system root or on a user disk. 


3.4.7 Global State 
If the installation procedure changes the global state of the system, 


except insofar as callbacks are concerned, it must restore the state 
before terminating. Some examples are as follows. 
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o If the installation procedure needs to INSTALL an {nage in 
order to complete the installation, it must deINSTALL the 
megs before exiting. rate pertains only to images needed 
during the installation itself. INSTALLS that must be done 

for product use should be done in the product-specific 

startup command procedure (see the SET STARTUP callback). 


3.5 The IvP 


Each product should provide an Installation Verification Procedure 
which verifies the completeness and accuracy of installation. If the 
kit's instaliation procedure declares that such a procedure exists, 
then VMSINSTAL will perform it after the installation is completed. 
VMASINSTAL does this by invoking KITINSTAL as folows. 


S$ Q@VMISKWD:KITINSTAL VMIS_IVP 


Thus, a kit's installation procedure must handle the request code 
VMIS_IVP if it declares an IVP. VMSINSTAL tries to set up a realistic 
a eng for the IVP before it runs. The following points are 
relevent. 


o ALL files will be in their final resting place. 


o If the installation procedure declared a product-specific 
startup procedure with the SET STARTUP callback, VMSINSTAL 
will invoke it before the IvP. 


o The default heed at | will be set to the kit's eres 
¢icectory. thus simulating a user's default directory in rea 
e. 


o The IVP cannot use callbacks. 


KITINSTAL.COM must exit back to VMSINSTAL with a status. Exit with 
VMIS_SUCCESS if the IVP is successful, or with VMIS_FAILURE if the IVP 
is unsuccessful. Note that VMSINSTAL does not attempt to ‘‘undo'’ an 
installation if the IVP fails. It is up to the installation procedure 
to ensure that the product is installed in its entirety and to further 
ensure that the IVP will not fail. This may sound sarcastic, but 
pesoranee to such a philosophy will produce the best installation 
procedure. 
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4 THE CALLBACKS 


This chapter describes the callbacks provided by VMSINSTAL. The 
syntax of each callback is proses ed in the standard pseudo-BNF 
format. Some of the metalinguistic symbols require’ further 
explanation. 
o KEYWORDS - sequares are specified in upper case. They must 
not be abbreviated in any way. 


© logical - A logical name to be defined by the callback. 
These Logica’ names must begin with the facility prefix fac$. 
By convention, use the logical name consisting sjaply of the 
refix if it will never be referenced after being specified 

n the callback. 


© symbol - A global symbol to be equated by the callback. 
Global symbols must begin with the facility prefix fac$. 
Again, use just the prefix if the symbol is never referenced. 


o dd - A disk and directory specification. References to the 
kit's working directory are made using the logical name 
VMISKWD. References to system directories are made using the 
logical name VMISROOT and an explicit directory, such as 
VMISROOT:CSYSLIBJ. Other references must specify an explicit 
device logical name (not device number) and a directory. A 
logical name may be used for the entire specification. At 
the time of reference, the disk must be mounted and the 
directory must exist. 


o nt - A file name and type. The type is always required, but 
no version may be specified. Neither logical names nor 
wildcarding are allowed. 


o ddnt - A complete file specification, consisting of a disk, 
eTractery. name, and type. A logical name may be used, but 
wildcarding is not allowed. 


© options - All options are specified as a comma-separated List 
of single-character codes. Embedded spaces are not allowed. 


S is returned if the 
$_FAILURE, a warning, 


ALL callbacks return an exit status. VMIS$_SUCCE 
callback could be completed without error. VM 
is returned if anything went wrong. 


S 
I 
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4.1 ASK 


This callback is used to ask the user a question and obtain a vali 
answer. It also supports the question mark help feature of VMSINSTAL 


$ VMISCALLBACK ASK symbol prompt Cdefault] Coptions] [help] 
Parameters 


d 


symbol - The name of a global symbol to be equated to the answer. 
The answer will be blank compressed, blank trimmed, uncommented, 
and upcased. 


prompt - A quoted got, containing the question to be asked. Do 

not include any trailing punctuation or whitespace; this is 

formatted automatically. 

default - The default answer. If not specified, the user must 

enter oS, ee Specify the default for boolean questions as 
or . 

options - A comma-separated List of single-character options. 


o 8B - Boolean. The user must answer YES or NO. The integer 1 
or 0 is returned as the answer. 


© D = Double space. A line is skipped before asking the 
question. 


o H-=- Help first. The help information is displayed before the 
question is asked. This is useful for very complicated 
questions. 

o I = Integer. The user must answer with an integer. 


o N- Null answer. A null answer is allowed. This only makes 
sense when a string is requested and no default is provided. 


o R- ane bell. The terminal bell is rung before the question 
is asked. 


o Se ace tne. The answer can be any character string. This is 
the default data type. 


o Z- CTRL/Z returned. If the user enters CTRL/Z, it is 


e 
returned as a string of the form ‘*7"', Without this option, 
CTRL/Z is ignored. 
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help - Help information. This can be queted String containing 
the help, or @ quoted procedure invocation. I! ; procedure 
invocation, it must begin with an at sign (a) and _ nvoke any 
procedure in the kit. Typteally it would invoke KITINSTAL.CO 
and pass it a request code, as follows: 


“@VMISKWD:KITINSTAL HELP_WHATEVER'' 


Because the request code does not begin with VMI$, it can't 
conflict with a request code passed by VMSINSTAL. 


4.2 CHECK_NET_UTILIZATION 


This callback is used to check that there are enough free blocks on 
the system disk to successfully complete the installation. The net 


mus 
block usage for a product must be obtained using the statistics option 
(see Chapter 5). 


$ VMISCALLBACK CHECK_NET_UTILIZATION symbol blocks 
Parameters 


symbol = The name of a global symbol, set to true if the required 
free blocks are available, false otherwise. 


blocks = The net number of blocks used by the product, that is, 
the er of blocks ultimately used when the installation is 
complete. 


4.3 CHECK_VMS_VERSION 


This callback is obsolete, but is retained in VMSINSTAL for 
compatability with V3. Use the VMISVMS_VERSION global symbol for 
these checks. (See the appendices for an example on how to decode 
VMISVMS_VERSION) 


This callback allows you to check the version of the running VMS 
system, in the event that your product has some dependency on the 
version. A test is performed to determine if the specified version 
requirements are met. 


$ VMISCALLBACK CHECK_VMS_VERSION symbol [version] (Cbaselevel) 
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Parameters 


symbol = The name of a giobal symbol which is set to true if the 
test is passed, false if not. 


version = This parameter is used when a released version of VMS 
is currently running. It is in the format vvu, and the test is 
passed if the specified version of VMS, or a later version, 

cays if the parameter is omitted, all VMS versions cause the 
est to fail. 


baselevel - This parameter is used when a field test baselevel of 
VAS is errant running. If in the format xxx, where xxx is the 
baselevel identification nag teh the leading X or Y, then the 
test is passed if the specified baselevel of VMS is running. If 
in the format eer: then the test is passed if a baselevel of 
VMAS in the specified tee is enigss If the parameter is 
omitted, all field test baseleve ® 


ls cause the test to pass. 


4.4 CONTROL_Y 
This callback must be invoked when the user enters CTRL/Y. The first 
command in every installation praecees must either be as specified 
below, or it must go to a label which performs cleanup and then the 
CONTROL_Y callback. 

$ ON CONTROL_Y THEN VMISCALLBACK CONTROL_Y 
Notes 


The callback returns a fatal status, which will result in the 
execution of your ON WARNING statement. If you do not include 


ever 
this line in every command procedure, and the user enters CTRL/Y 
at the wrong time, all hell breaks loose. 


4.5 CREATE_ACCOUNT 


This callback is used to create a new account in SYSUAF.DAT. It 
should be used sparingly, if ever. 


$ VMISCALLBACK CREATE_ACCOUNT username qualifiers 
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Parameters ' 
username - The username to be associated with the account. 


qualifiers - A sequence of qualifiers as accepted by the ADD 
command of the AUTHORIZE utility. The qualifiers must be 
enclosed in quotation marks. 


Notes 


In most instances, software products need not create new 
accounts. As an example, it is usually unnecessary to create a 
system management account for your product, because the $y2 stem 
manager can perform all management from the standard SYSTEM 
account. Your product must not assume that it knows the UIC for 
@ new account, but must ask the user. 


4.6 CREATE_DIRECTORY 


This callback is used to create a directory on the system disk or some 
other user disk. 


$ VMISCALLBACK CREATE_DIRECTORY {SYSTEM hierarchy) Cqualifiers) 
{USER dd ) 


Parameters 


SYSTEM heirarchy - This combination of parameters is used when 
you want to create a ehreqsery # enfernneth ee ete rete, The 
directory name must not begin w example, SYSTEM 
SYSHLP.FOO will create the » as Te, VRISROOTS CSYSHLP FOO). 


USER dd = This penpraye ren is used to create an arbitrar ry 
directory auser disk. For example, USER WRKD$:CSNORK) wil 
create the top-levet " SNORK directory on the user work disk. 


pat iewere - i. ye age - Pi ag hbah 2 yi —. a hg rad Mo 

ommand. or . of followi ng: 
7OUNER UIC, YPROTECTION® ele SION_LIMIT. mothe a. T. must be 
enclosed in quotation marks. 


Notes 
Do not create directories on a meee disk unless sheolurety 


necessary. Most layered products are associated with 
particular system root and thus should appear in that root. 
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4.7 DELETE_FILE 


This callback is used to delete an oppotete file created by a previous 
installation. Remember, BYPASS privilege is not enabled. 


$ VMISCALLBACK DELETE_FILE ddnt 
Parameters 
ddnt = The complete specification of the file to be deleted. 


4.8 FIND_FILE 


This callback is used by VMSINSTAL whenever it must locate a _ file 
epec ti tee in another callback. You must also use FIND_FILE itself 
when you need to reference a system file for some purpose not 
supported by a callback. Files in the kit's working directory may be 
referenced directly. 


$ VMISCALLBACK FIND_FILE logical ddnt Cdefault) locate Csymbol] 
Parameters 


Logical = A logical name which will point at the file when the 
callback returns. ALl references to the file from that point on 
must be made via the logical name. 


ddnt - A full or partial specification of the file to be located. 


default - A full or partial file specification to be used as the 
default when parsing the previous parameter. 


locate - A comma-separated list of single-character codes that 
specifies how the file is to be located. The items in the list 
=a be chosen from the following, and must appear in the order 
shown. 


WwW - kit's Working directory. Check the kit's working 
directory for a file with the matching name and type. 


S - as Specified. Check the directory specified by the ddnt 
and default parameters. If the file is not found there, and 
this is a small disk system, check the corresponding 
directory on the Library disk, if any. 
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E- Error. If the file has not yet been found, produce an 
error message and exit with status VMIS$_FAILURE. 


0- ~ tt tg ah hae root. Use the system-specific root, if 
insta “ne to @ common root, when searching for a matching 
name and type. 


syabet - This optional giopet symbol will be equated to reflect 
the results of the callback, as follows. 
SYMBOL VALUE MEANING 
“wr Wwas included in the locate | 


i 
and the fiie was found in the k 
working directory. 


st 
it's 


_ 3 was included in the locate List, 
and the file was found in the 
specified directory. 


+. we E was included in the locate List, 
and an error was reported. 


None of the above. 
Notes 


If you ever try to reference a system file directly, without 
going through some callback, your installation procedure will be 
prone to breakage. 


4.9 GENERATE_SDL_DEF INITIONS 


This callback is used to generate SDL definitions. The generated 
files will be located in the kit's working directory with the language 
specific file extensions. 


$ VMISCALLBACK GENERATE_SDL_DEFINITIONS module_file language - 
Cqualifiers) Coptions) 


Parameters 


module file - The name of the module to be extracted from 
STARLETSD.TLB for processin by SDL. If the module name is 
preceded % an ‘‘a’’, then module_file is assumed to be a file, 
found in VMISKWD: (i.e. shipped on the kit). This file should 
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contain one module name per Line. VMISKWD:.DAT is used as the 
1 tty file specification when searching for the module name 
ile. 

Language - The name of any supported SDL output language. If 
more than one sangenee output is desired, separate them with a 
comma, and enclose the list with quotation marks. 

qualifiers - This is an optional List of one or more valid SDL 
qualifiers which will be applied to the SDL command. This allows 
special processing to be done on the SDL output at the discretion 
of the layered product. The qualifiers must be enclosed in 
quotation marks. 

options - This is an optional list of single character options, 


separated by commas. There are none currently defined and is 
reserved for future expansion. 


4.10 GET_SYSTEM_PARAMETER 


This callback is used to obtain the current value of a system 
parameter. 


$ VMISCALLBACK GET_SYSTEM_PARAMETER symbol name 
Parameters 


symbol - The name of a global symbol to be equated to the value 
of the parameter. 


name - The full name of the parameter to be obtained. 
Notes 
There is no way to set the value of a system parameter. You may 


make recommendations to the system manager, but you cannot set 
the parameters. 


4.11 MESSAGE 
This callback is used to display a message in the standard VMS format. 
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$ VMISCALLBACK MESSAGE severity id text ... 
Parameters 


severity - The severity of the message. Use the standard codes 
- I, W, and —€. You may not generate a fatal error. 


id - The mnemonic identification of the message. This allows 
cross-referencing in your installation guide. 


text - The actual text of the message(s). You can specify up to 
three message lines, the first of which will be prefixed with a 
percent sign (%) and the remainder with a hyphen (-). 

Notes 
It is not necessary to use this callback when Stepley ing Large 


blocks of explanatory text. You should use it when displaying 
important messages about the status of the installation. 


4.12 PATCH_IMAGE 
This callback is used to patch an existing native-mode image. 


$ VMISCALLBACK PATCH_IMAGE logical patch-nt Cimage-ddrit] - 
Coptions) 


Parameters 
logical - A logical name which will point at the patched image 
when the callback returns. All references to the image from that 
point on must be made via the logical name. 
patch-nt - The name and type of the file containing patch 
commands. All desired patch commands, and ony patch commands, 
must be present in this file. The file must reside in the kit's 
working directory, and may be deleted after the callback returns 
in order to save disk space. 
image-ddnt - The full specification of the image to be patched. 
options = a comma-separated List of options. 


J = Journal. Create or update a patch journal in the same 
directory as the image. 
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o K = Keep. Do not purge old versions of the image. 


o A_= Absolute. Use absolute mode when patching image 
(PATCH/ABSOLUTE...) 


| If the “aay? is not specified in the callback, it is assumed to 
be specified on the first Line of the patch command file. This 

line consists of an exclamation point and the full image 
| spec ification. Furthermore, if an aptten List is present after 
the specification, it is merged in with the option List specified 

in the callback. 


4.13 PRINT_FILE 
This callback is used to queve a file to SYSSPRINT for printing. 
$ VMISCALLBACK PRINT_FILE ddnt [copies] 
Parameters 
ddnt - The full specification of the file to be printed. 
| copies - The number of copies to be printed. The default is one. 


4.14 PRODUCT 


This callback provides a simple facility for adding product-specific 
callbacks tc VMSINSTAL's caliback repertoire. When a set of products 
form a logical grouping (e.g.. VAX Information Architecture, RSX/VAX), 
there may wary well be some additional callbacks which the products in 
the group would like to share. In this case, the base product in the 
group ‘e.g... COD, RSX) can preside a command procedure conte tntag 
additional callback logic. The PRODUCT callback is the window throug 
which installation procedures obtain the services of that procedure. 


$ VMISCALLBACK PRODUCT procedure:callback parameter ... 
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Parameters 


procedure - The name of the procedure which he pet the required 
ae It is assumed to reside in SYSSUPDATE with a file type 
° ‘ 


parameter - The remainder of the parameters are simply passed on 
to the product-specific callback. 


Notes 


The status returned by the PRODUCT callback is the status 

returned by the product-specific callback. Conventions for 

ete praducesanees* te callback procedure are outlined in 
x ° 


callback - The name of the desired callback. 
| 


4.15 PROVIDE_DCL_COMMAND 


This callback is used to add a DCi command to the DCL command tables. 
If the command already exists, it is replaced. 


$ VMISCALLBACK PROVIDE_DCL_COMMAND nt 
Parameters 
nt - The file name and type of the CLD file. It must reside in 
the kit*s working directory, and may be deleted after the 
callback returns in order to save disk space. 


Notes 


The command is also added to the active process command tables. 
vou may add more than one command by using the callback multiple 
times. 


4.16 PROVIDE_DCL_WELP 


This callback is used to insert help into the DCL help library. If 
the help already exists, it is replaced. 
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| Parameters 


| nt = The file name and type of the help text file. It must 


$ VMISCALLBACK PROVIDE_DCL_HELP nt 
| 
| reside in the kit's working directory, and may be deleted after 


the callback returns in order to save disk space. 
Notes 


You aey provide more than one help entry by using this callback 
multiple times. Only a top-level help entry may be inserted. 


4.17 PROVIDE_FILE 
This callback is used to provide a complete new file as part of the 
software product. If the file already exists, a new version is 
created. 
$ VMISCALLBACK PROVIDE_FILE Logical nt dd Coptions) 
Parameters 
fo - A logical name which will point at the file when 
callback returns. All references to the file from that point on 
must be made via the logical name. 


nt - The file name and type of the file being provided. It must 
reside in the kit's working directory. 


dd - The target disk and directory for the file. 
options - A comma-separated List of options. 
o K = Keep. bo not purge old versions of the file. 


L - Library. Put the file on the library disk if this is a 
tailored system. 


0 O0- Syetenmsper ific. Move the file to the system-specific 
root if installing to a common root. 

Notes 
no 


Do not use this callback to provide am image. See the 
PROVIDE _IMAGE callback. 
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(4.18 PROVIDE_ IMAGE 

| This callback is used to provide a complete new image as part of the 

software product. If the image already exists, a new version is 

created. | 


$ VMISCALLBACK PROVIDE_IMAGE Logical nt dd Coptions] [Ceco-list] 


Parameters 


Lopicet - A logical name which will point at the image when 
callback returns. ALl references to the image from that point on 
must be made via the logical name. 


Carr | Ch i ed ed be 


reside in the kit‘s working directory. 


nt - The file name and type of the image being provided. It must 
dd - The target disk and directory for the image. | 


options = A comma-separated List of options. 


bl ed tel ceed 


o € = ECO List. The following parameter specifies a list of 
ECO levels which are to be set in the image. 


o I = IMAGELJIB. Add a sharable image to IMAGELIB.OLB so that 
it will be automatically searched by the Linker. 


ou <e 


o K = Keep. Do not purge old versions of the image. 


Oo Lt = Library. Move the image to the library disk if this is a 
tailored system. 


root if installing to a common roo 


Somers erece 


eco-list - A comma-separated Li 
to be set in the image. Th 
option is present. 


st of ECO level numbers which are 
is parameter is used only if the — 


Notes 


If the image was INSTALLed before the installation began, it will 
be reINSTALLed afterwards. Compatibility-mode images must also 
be provided with this callback. 
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o O = System-specific. Move the 9 to the system-specific 
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(4.19 RENAME_FILE 

‘This callback is used to rename a file which was created by a previous 
installation. The file mame and type can be changed, but the file 

cannot be moved from one directory to another. 


SVMISCALLBACK RENAME_FILE ddnt new-nt 


Parameters 
new-nt - The new file name and type for the file. 
4.20 RESTORE_SAVESET 
This callback is used by VMSINSTAL to restore the primary kit saveset. 
You may also use it to restore savesets other than the primary one. 
$ VMISCALLBACK RESTORE_SAVESET saveset Coptions] 
Parameters 
saveset - The single-letter identification of the saveset to be 
restored. The entire contents of the saveset are restored into 
the kit's working directory. If a file to be restored already 
exists in the directory, an error results. 
options - A comma-separated List of options. 

Oo N - Next volume. The saveset begins on the next volume of 
the distribution volume set. VMASINSTAL will figure that out 
if you don't specify this option, but with a few funny 
messages appearing on the console. 

Notes 


Not ail savesets need be restored, but they must be restored in 
alphabetical order. Restored files will have owner UIC (1,4) and 
whetever protection they had when saved. This protection should 
be as specified in section 3.3.1; a future enhancement to 
VMSINSTAL may force this to be true. You must alter ths owner 
UIC and protection after files are restored. 


ddnt = The complete specification of the file to be renamed. 
_ 
i 
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4.21 SECURE_FILE 

This callback is used to alter the security information associated 
with files. It should only be used by a product for which security is 
a major feature, such as a hospital application. In most cases, the 
default system security is fine. 


$ VMISCALLBACK SECURE_FILE ddnt Cowner-uic] [protection] 


altered. 


ws act - The new UIC for the files, in the standard format 
g.m 3 


protection - The new protection for the files, in the standard 
format. Do not enclose the protection string in parentheses. 


Notes 
You have to be very careful if your installation pes oe neg 
files which have special security. pont, ee that generates a 
new version of the file, such as TCH_IMAGE, will cause the 
default security to be assigned. fou. must ej oop bays! A. the 


security back to ey! special values. The security on V 


system 
e altered. 


files must never 


4.22 SET IvP 


This callback is used to determine whether or not the product's IVP is 
run after the installation. 


$ VMISCALLBACK SET IvP fves? Coptions] 
{ASK} 
Parameters 
YES - Run the IVP. 


- There is no IVP supplied with this product. This is the 
dotault. 


Parameters 
ddnt - The full specification of the file whose security is to be 
28 
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ASK = There is an IVP, but ask the user if it should be run. 
options - A comma-separated List of single-character options. 
o H = Help first. When in ASK mode, this option specifies that 


the help information for the question be displayed before the 
question is asked. 


PariteT 44444 4 4 4 


4.23 SET PURGE 


cS callback is used to specify whether or not files Ag peg ee by this 
are to be purged during or after the installation. 

| 
4 


$ VMISCALLBACK SET PURGE pres? Coptions] 
{ASK} 


PAHAAPARA PHPMHAMMHMHHKHHKHEFROOM 


dee sesece 


Parameters 
YES - Purge all files during or after the installation. 


NO = Do not purge file during or after the installation. This is 
the default. 


ASK - Ask the user. 


Nee 


options - A comma-separated list of single-character options. 


ood Ore er 


question is asked. 


Notes 


If a file was provided with callbacks that specified the keep (K) 


© H - Help first. When in ASK mode, this option specifies that 
the help information for the question be displayed before the 
option, it is never purged. 


Se en 1 ~ eee 
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4.24 SET REBOOT 

This callback is used to ppec tty, that a system reboot is necessary 

after the installation. is callback is reserved for VMS updates and 
upgrades; layered products should never reboot. 


$ VMISCALLBACK SET REBOOT ayest 


Parameters 
YES - Reboot after the instailation. 
NO - No reboot is necessary. This is the default. 


PAAMAMM AME MOM 
ADE -OQNR DN eee == - oO 


4.25 SET SAFETY 
This callback is used to specify the safety level of the installation. 


$ VMISCALLBACK SET SAFETY {YES peak} 
oe DITIONAL pooks 


Parameters 


YES peak - System safety should be optimized at the expense of 
disk blocks. This option is the default, and produces the 
highest degree of recovery capability should the system crash 

no 


during the snotetiotten. or in safety mode does not 
guarantee the success of agg th ions performed while other 
rocesses are active. The peak parameter specifies the peak 
Shock utilization during a safety ae installation. This number 


—_— be obtained using the statistics option (see Chapter 5). 
CONDITIONAL peak - If the specified peak blocks are available, 
then optimize sofety: otherwise do not. This is the option that 
should specified if at all possible. 


NO - System safety should be ignored in order to save disk space. 


VMI 
$1 
$$ 
$! 
$ 6 
$V 
$! 
$7 
$s 
$V 
$V 
$V 
$! 
$! 
$! 
$V 
$1 
$! 
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4.26 SET STARTUP 


This callback is used to specify ny product-specific startup 
procedure so that it can be invoked after the installation and before 
the IVP is run. This callback does not put the installation procedure 
in SYSSMANAGER; use a PROVIDE_FILE callback for this purpose. This 
callback does not tell the syste™ manager adout the procedure. 


$ VMISCALLBACK SET STARTUP nt 


Parameters 
nt - The file name and type of —_ product-specific installation 
procedure. It is assumed to ultimately reside in the SYSSMANAGER 
directory. 

Notes 


By isolating all proquctnepes t 7st stort activities in one 
procedure, you minimize the changes to SYSTARTUP.COM, make the 
system manager's job easier, and allow a simulation of startup 
before the IVP is run. 


4.27 SUMSLP_TEXT 


This callback is used to edit an existing text file or library member 
with the SUMSLP editor. 


$ VMISCALLBACK SUMSLP_TEXT logteat command=-nt - 
({ddnt FILE} old-checksum Cnew-checksum]) Coptions]] 
{ddnt,member type) 


Parameters 


feptcat - A logical name which will point at the edited file or 
Library when the callback returns. AlLl references to the file or 
Library from that point on must be made via the logical name. 


command-nt - The name and type of the file containing SUMSLP edit 
commands. All desired commands, and only commands, must be 
present in this file. The file must reside in the kit's working 
directory, and may be deleted after the callback returns in order 
to save disk space. 
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ddnt FILE = The full Spee ct teat ten of the text file to be edited. 
If you want to edit a library member, use the following format. 


| 

ddnt,member type - The full specification of the Library 

| containing the member to be edited. Immediately following is a 
comma and the name of the member. The type parameter specifies 
the type o TEXT. 


f the Library: HELP, MACRO, 


old-checksum - The checksum of the file or member prior to 

editing. This is used by VMSINSTAL to ensure that you are 

editing what you think you are editing. This checksum is 
ai 


PRAPARAMKMMMM 
AN -—--O<-- Me 


which will be shipped with 


calculated ysing the Checksum ody | 
he ls, VMSINSTAL reports an 


the new VASINST If the checksum 
error and returns unsuccessfully. 


new-checksum = The checksum of the file or member after oetEe- 
This is used by VMSINSTAL if the old checksum does not match the 
file or member, so that it can produce any informatory message 
rather than an error message. 


options - A comma-separated List of options. 


<<s--- 


<= 


o K = Keep. Do not purge old versions of the file. 


<<< 


Notes 


If the file or orery member is not speci tted in the callback, 
it is assumed to be specified on the first Line of the SUMSLP 
command file. This Line consists of the characters dash, 
semicolon, exclamation point ‘-;!) followed by parameters 4, 5, 
6, 7 and & as described above. 


4.28 TELL_OA 


There is a Quality Assurance (QA) Anes | at Spit Brook which installs 
layered product kits on various baselevels of VMS. We hope to catch 
proscene at an early stage, so that the fixes to VMS and/or the 
ayered products can be made in a timely fashion. 


COHVO- VHX <------ 
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The QA yroup will check many aspects of your product installation. If 
they find that you are going something in a nonstandard fashion, they 
will complain to you. If this nonstandard operation is essential, 
there is no point in wasting everyone's time with the complaint. This 
callback is used to bring these essential deviations to the QA folks’ 
attention. When the installation is done in QA mode (see Chapter 5), 
information specified by TELL_QA is displayed on the terminal. When 


<--H9 


PROS SESVOS 
i) 


vo 


32 


[2 


. 4 
irun normally, such as at a customer site, the information is not 
| displayed. 

| $ VMISCALLBACK TELL_QA message 
| Parameters 


poeenge - A quoted string to be displayed when installing in QA 
e. 


Notes 


If you have a special problem and consult with a VMS developer, 
you may be told to include this callback in front of the 
resulting installation code. 


4.29 UPDATE_ACCOUNT 


This callback is used to update an account in SYSUAF.DAT. It should 
be used sparingly, if ever. 


$ VMISCALLBACK UPDATE_ACCOUNT username qualifiers 
Parameters 
username - The username that identifies the account. 
qualifiers - A sequence of qualifiers as accepted by the MODIFY 
command of the AUTHORIZE utility. The qualifiers must be 
enclosed in quotation marks. 
Notes 


You may only update an account that was originally created by 
your product. Please also see the notes under CREATE_ACCOUNT. 


4.30 UPDATE_FILE 


This callback is used to update an existing file. It is only used 
when updating the file in place, that is, por Soratng an update that 
modifies an existing copy of the file. First issue the U DATE_FILE 
callback, and then reference and modify the file via the logical name. 
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| $ VMISCALLBACK UPDATE_FILE Logical ddnt 

Parameters 
Lopiget - A logical name which will potas at the file when 
callback returns. ALL references to the file from that point on 
must be made via the logical name. 
ddnt - The complete specification of the existing file to be 

no 

updated. You may not create a new version of the file. 

Notes 
This callback is mot used to update Libraries (see 
UPDATE_LIBRARY). If you need to create a new version of an 
existing file, and none of the other callbacks are sufficient for 
your purposes, then create the new version in the workin 


directory. Once the new version is ready, use the PROVIDE_FIL 
callback to replace the old version. 


4.31 UPDATE_LIBRARY 
This callback is used to update an existing Library. 


$ VMISCALLBACK UPDATE_LIBRARY logical Lib-ddnt type - 
qualifiers Cfile-ddnt] 


Parameters 
logical - A logical name which will point at the Library when 
callback returns. All references to the Library from that point 
on must be made via the logical name. 


Lib-ddnt - The complete specification of the existing library to 
be updated. 


type - The type of the Library: HELP, MACRO, OBJECT, SHARE, 
quelifiers - A sequence of qualifiers for the Librarian. The 
qualifiers must be enclosed in quotation marks. 

file-ddnt - The full specification of the input/output file for 
the Librarian, if requires by the qualifiers. This specification 


Sey include wildcards. The file may be deleted after the 
callback returns in order to save disk space. 
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Be careful not to rely on defaults in the qualifiers. 


S$ suggested that you use the /REPLACE operation 
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/INSERT. 
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5 VMSINSTAL OPTIONS 


VASINSTAL accepts various options which can simplify the creaticn and 
debuggi of your installation procedure. You request these sey rene 
by eppenting two or three parameters to the invocation of VMSINSTAL. 


$ @VMSINSTAL product device OPTIONS List [root] 


It requires two parameters so you don't do it accidentally. The 
— parameter is a comma-separated List of option letters, as 
ollows. 


o A-= Auto-answer. This feature allows you to pre-answer the 

questions asked yeh the installation of a product and then 

se the answers a a later date. If the file 

SYSUPDJfacvvu.ANS exists, VMSINSTAL uses the answers in the 

file and does not bother asking you the questions. If there 

s mo such file, VMSINSTAL asks you the questions 

interactively and records the answer in a new file for later 
use. 


© 8B - invoked during Booting. This option is used when 
VMSINSTAL is invoked from STARTUP.COM after a crash during 
installation. 


o C = Callback trace. VMSINSTAL traces all callbacks and Lists 
them in the file CSYSUPDJ facvvu.CBT. 


o D = De mode. This option is used in the orn, + Set of 
VASINST itself. Do not use it when debugging your 
installation procedure. 


o G = Get savesets. This option is used to copy the savesets 
comprisi a kit into a disk directory for Later 
installation. All kit savesets are copied, but no 
installation is performed. Parameter 5 can specify the disk 

and directory into which the savesets are to be copied. 


o K = Kit Gebug mode. VMSINSTAL passes a boolean parameter to 
the «it's installation procedure when requesting that it do 
an installation. This parameter reflects the presence or 
absence of the K option. The kit's installation procedure 
can then modify its behavior as desired. 


o L = file Log. VMSINSTAL defines special symbols for commands 
so that all file activity is logged to the terminal. This is 
why command verbs cannot be abbreviated. Normally, file 
a.tivity is not logged. 


PRAMMM 
-O0-- 
>> 


PRAAMAMMMM 
tm me Mmmm 
= 


v 
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7 > 4 s oe 2 
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Q = QA mode. This — specifies that the installation 
should be done in QA mode. Any TELL_OA callbacks performed 
by ~~ kit's installation procedure are logged to the 
erminal. 


R = alternate Root. The product is installed in a system 
root other than that of the running system. Parameter 5 must 
specify the root in the forma ddcu:(SYSn.J". This 
alternate root must contain a full complement of VMS 
software. The VMS system in the alternate root must be at 
the same version/update level as the a system. If the 
installation procedure references ~ other layered products, 
a versions of the products on the running system will be 
used. 


S$ - Statistics report. VMSINSTAL produces a statistics 
report in the file CSYSUPD]facvvu.ANL. This report contains 
a description of the hardware and software on which the 
installation was performed, disk usage statistics, and a list 
of files added, deleted, modified, and accessed by the 
installation. Correct disk —— statistics require that the 
system disk contain a full complement of VMS software and 
enough free blocks for an installation in safety mode. Note 
that the statistics pertain ety to the system disk, so that 
the Library disk on a small disk system is not included. 
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$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
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A SAMPLE INSTALLATION PROCEDURE 


The following is the installation procedure for FMS. This procedure 
is ‘ — good sample for analysis by would-be installation procedure 
mplementers. 


KITINSTAL.COM 
COPYRIGHT (C) 1983 B 


DIGITAL EQUIPMENT CORPORATION MAYNARD 
MASSACHUSETTS. ALL RIGHTS RESERVED. 


Y OTHER 
RSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY TRANSFERRED. 


THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND 
SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT CORPORATION. 


DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS 
SOFTWARE ON EQUIPMENT THAT IS NOT SUPPLIED BY DIGITAL. 


! 

1 

' 

] 

! 

' 

1 

1 

: ! NO Bes HIS SOF TW 

: pekehe MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO A 

' 

' 

' 

1 

! 

! 

' 

SSOP S HTH A EEE REA AEA AERA TE ERE EERAAAREHEEEREAAEeee eee ee eeeeeeeeeee 
This procedure installs VAXFMS V2.1 on VMS using VMSINSTAL 
Setup error handling 


! 

' 

' 

' 

' 

ON CONTROL_Y THEN RISC BAER CONTROL_Y 
ON WARNING THEN GOTO ERR_EXIT 
' 

' 

IF 
IF 
EX 


The 
cras 


Handle INSTALL, IVP and unsupported parameters passed by VMSINSTAL 
1 “Eat. *VAIS_INSTALL* — ws INSTALL 
1 EQS. “‘VMIS- i‘: THEN GOTO IVP 
IT VAIS_ UNSUPPORTE 
INSTALL: 


Let VMSINSTAL know we have an IVP which must be executed, 
and that all replaced files are to be purged. 


ISCALLBACK SET IVP YES 
ISCALLBACK SET PURGE YES 


Check for valid VMS version 
Will install to any version 3.2 or Later. 


etm gh sie eRe t= i Ons a RR ISAS PA AES 


' 
i 
i 
i 
vm 
vA 
' 
i 
i 
i 
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VMISCALLBACK CHECK_VMS VERS 10" VAXFMSSVMS 032 
IF .NOT. VAXFMSSVMS THEN VMI ALL ay MESSAGE E BADVMS - 

3 kit requires Versio or a subsequent version of VMS" 
if NOT. VAXEMSSVE THEN EXIT vMi FAILURE 
i Check for enough free blocks on system disk. 
| Neda minimumof 5000. . 
VRISCALLBACK | = CK_NET_UTILIZATION VAXFMS$ 5000 
IF ml, TREN QMISCALLBACK MESSAGE E NOSPACE - 

a ae does not contain a free blocks to install FMS" 

" NOT. YWAXEMSS THEN EXIT VMIS_FAILURE 
i 


Check for VzZ.0 FMS 


q 
$ 
$ 
$ 
t 
& 
% 
$ 
7 
$ 
4 
$ i 
4 VMISCALLBACK FIND rite VAXFMSS VMISROOT:CSYSEXEJFMSFED.EXE - 

"'§ VAXFMSSV2F 
. If VAXFMSSV2FED .EQS. ‘'S'’ THEN GOTO 20$ 'v2.0 FED IS THERE 
: ; Check for V1 FMS 
$ VMISCALL BACK ALINDGFILE VAXFMSS VMISROOT: [SYSEXEJFED.EXE ~ 
$ IF VAXFMSSV\FeD EQS. °’S** THEN GOTO 10$ 'v1 FED IS THERE 
$ VMISCALLBACK F INb FILE VAXFMSS VMISROOT:CSYSEXEJFUT.EXE - 
$ IF VAXFMSS$VIFUT .EQS. ‘'S*’ THEN GOTO 10$ ‘v1 FUT IS THERE 
; GOTO 20$ 
: } Clean up parts of Version 1 
. Remove the old FDV object modules from STARLET.OLB. 
$ 10S: 
$ VMISCALLBACK UPDATE LIBRARY VAXFMSSSTARLET VMISROOT:CSYSLIBISTARLET.OLB - 
$ OBJECT “*/DELETE=(F DV, FDVMSG, FDVDAT, FDVERR,FDVTIO,FOVXFR,HLL, HLLDFN)"’ 
$ 
$ 
$ ! 
£ 
4 
$ 
£ 
$ 
$ 
$ 
g 
$ 
$ 


Save FMS V1 FDVSHARE.OPT and FDVSHR.EXE by renaming it to *.0LD 


VAISCALLBACK XFASRSHARE STA aa VMISROOT: CSYSLIBJFDVSHARE.OPT - 
If VAXFMSSSHARESTAT NES. Ase 1 THEN GOTO 15$ 

CKUP VMISROOT = CSYSL IBF DVSHAR E.OPT VMISKWD:FDVSHARE .OLD/OWNER=ORIGINAL 
ISCALLBACK DELETE FILE VMISROOT:(SYSLIBJFDVSHARE .OP 
ISCALLBACK PROVIDE_ FILE VAXFMS$ FDVSHARE.OLD VMIS$ROOT:CSYSLIBJ 
$: 
I 


SCALLBACK FIND FILE VAXFMSS VMISROOT: [SYSLIBJFDVSHR.EXE ~ 
F_VAXFASSSHRSTAT. SMES. “'S"" THEN GOTO 208 
BACKUP. VAISROOT : LSVSLIBJFDVSHR. EXE. VAISKUD:F DVSHR..OLD/OWNER=ORIGINAL 


39 


CALLBACK DEL 


E BIFDVSHR, 
CALLBACK PROV 


TE FILE VMISROOT:CSYSLIB EXE 
1 | OLD VMISROOT:CSYSLIB) 


EFI 
DE_FILE VAXFMSS FDVSHR. 


a 
Pew 
wom 


20$: 

Restore saveset B and go. 

VMISCALLBACK RESTORE_SAVESET 6 

Link and supply to system the FMS and FDV Message files 
LINK /SHAREABLE=VMISKWD : FMSMSG VMISKWD : FMSMSG 
VMISCALLBACK PROVIDE IMAGE VAXFMSS$ PROS Exe B by ae :CSYSMSG) 


LINK /SHAREABLE=VMI$RWD 
VMISCALLBACK PROVIDE_ IRAGE VAXFMS$ FDVMSG. EXE VMISROOT:CSYSMSG) | 


ve 
ve 
' 
' 
' 
‘ 


Link Form Driver and FIO as shared Library. 


eutlé the image. NOTE THAT THE GSMATCH NUMBER MUST BE UPDATED 
FOR EACH RELEASE AND POINT RELEASE! 


| NK /SHAREABLE = VIISKUD:FDVSHR ~ 
VMISKWD : TIOFMSMSG.OPT/OPTIONS, 
SYSSINPUT:/0PT 
, VMISKWD :FDVL 18/ INCLUDE=F DVSXFR 
VM vni $kup B/LIB 


0:2 VMISKUD: :FDVLIB/ INCLUDE, = = ioe - 


PHAPAAAPAAAAPAAAPAAPAAPAACEAAHOANYE 


( casasesacasace: 


o 
_ 
Cc 
w 
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nun 
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VMISKWD :FDVLIB/LIBRARY 
fEOOAr °461 


Insert 1 module to STARLET 


VMISCALLBACK UPDATE LIBRARY VAXFMSSSTARLET VMISROOT:CSYSLIBISTARLET.OLB - 
JECT *'/REPLACE’* VMISKWD:FDVPLITRM.OBJ 


Put V2 FDVSHR in the System Library and install in IMAGELIB 


‘ 
i 
' 
VRISCALLBACK PROVIDE_IMAGE VAXFMSS$ FDVSHR.EXE VMISROOT:CSYSLIB) | 
i 
L 


: 
“— 
oO 
x 
“un 


<-=+=: 


Form Upgrade Utility 


INK /EXECUTABLE=VMISKWD : FMSFUU 
VMI SKWD : FUUL 1B/L IBRARY/ INCLUDE =FUUSTOP, - 
VAISKUD VIS 


PAHAPRAPFARAH PCPS 
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The 


VMISKWD:FMSPTR 
SYS$INPUT/OPTION 
We pests : FPDVSHR/ SHAREABLE 
$ Forms Application Aids 
$L 


INK ny ey orgy big FMSFAA 
MISKWD AALIB/LIBRARY /INCLUDE=F AASMAIN, 


VRISEUD: FRSPTR 

SYS$IMPUT/OPTION 
1 $kWD : FDVSHR/SHAREABLE 
Form Librarian 
L 


IWK gi Me tay bart FMSFLI = 
VMISKWD FLILIB/LIBRARY/INCLUDE=FLISDRIVER, - 


$k 
VRISKUD:FRSETR = 
$KWD : FDVSHR/SHAREABLE 


yn 
$ Form Language 
$L 


INK By ge ba te FLG = 
VMISKWD : F LGLIB/LIBRARY/INCLUDE=DRIVER, - 


VAI SK KW : FMSP 

Sy SS INPUT/OPT TON 
$KWD : FDVSHR/SHAREABLE 

Form Tester 


LINK iM may bat FMSFTE = 
VMI SKWD :F SEL TE/LIGRARY/ IECLUBES =FTE,=- 


VaisKuD; FMSPT 
SY YSSINPUT/OPTION 
$KWD : FDVSHR/SHAREABLE 
Form Editor 
ISKWD:FMSFED - 
B/ INCLUDE=F EDSFED/LIBRARY,- 
B/ INCLUDE =F DV$VECTOR/LIBRARY,- 
B/ INCLUDE=F DVSMEMRES/LIBRARY,- 
VMISKWD: R,= 
SYS$INPUT/OPTION 
$KWD : FDVSHR/SHAREABLE 
Add FMS and qualifiers to DCL 
ISCALLBACK PROVIDE_DCL_COMMAND FMSDCL.CLD 


Now update the system help Library 


- 


POOMOOrS 
ne acace 
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PAHAAPAA PPHPHHAPKHKAKHEFEHOCECS 


PR H HAHFPAPHAHAFEFEHAGHHOAH PGHEKHSCES 


YRISCALLBACE PROVIDE_DCL_HELP FMS.HLP 

Now put everything in its place 

VMISCALLBACK PROVIDE IMAGE VAXFMSS FMSFUU.EXE VMISROOT:CSYSEXE 
VMISCALLBACK PROVIDE_IMAGE VAXFMSS FMSFED.EXE VMISROOT:(SYSEXE 
VMISCALLBACK PROVIDE_IMAGE VAXFMSS FMSFAA.EXE VMISROOT:LSYSEXE 
VMISCALLBACK PROVIDE_IMAGE FMSFTE.EXE VMISROOT:LSYSEXE 
VMISCALLBACK PROVIDE_IMAGE VAXFMS$ ha oh Le ISROOT:LSYSEXE 
VMISCALLBACK PROVIDE_IMAGE VAXFMSS FMSFLI.EXE VMISROOT:(CSYSEXE 
VMISCALLBACK PROVIDE-FILE VAXFMS$ HLL1 .OBJ VMISROOT:CSYSLIB 


Give System Manager an FMS Startup procedure 


VMISCALLBACK PROVIDE_FILE VAXFMSS = 
FASTARTUP.COM VMISROOT:CSYSMGR] K 


Tell VMSINSTALL about FMSTARTUP 
VMISCALLBACK SET STARTUP FMSTARTUP.COM 
TYPE SYSSINPUT 


VAX=-11 FMS utilities have built successfully. 
Continuing installation... 


acess Ceacece 


: Provide the FMS Sample Application Programs 

: Create CSYSHLP.EXAMPLES.FMS] (check to see if it is there, first) 
we Pe Te EAS pearnes VMISROOT:CSYSHLP.EXAMPLESIJFMS.DIR - 
IF VAXFMSSEXAMPSTAT .EQS. ‘'S'’ THEN GOTO 30$ !THEN IT'S THERE 
VMISCALLBACK CREATE_DIRECTORY SYSTEM SYSHLP.EXAMPLES.FMS 

308: 

! Create SMPVECTOR and SMFMEMRES - Need to tell system that FMSFAA 
! and FOVSHR are temporarily in VMISKWD in order to use the DCL 

: commands necessary. 


DEFINE FDVSHR VMISKWD:FDVSHR.EXE 
DEFINE FMSFAA VMISKWD:FMSFAA.EXE 


FMS/VECTOR/OUTPUT=VMI$KUD : SMPVECTOR - 


vA AMP. 
FMS/MEMORY /OUTPUT=VMISKUD : SMPMEMRES = 
VMISKWD : SAMP.FLB/FORM=(HELP_KEYS,HELP_MENU) 


' 
DEASSIGN FDVSHR 


a 
4 


< 


< 
Cc 
man 


$ 
$! 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$! 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
of 
$ 
$ 
$ 
$ 
$ 


< 
c 
— 


PR PRR PMOS 


< 
fon 


; DEASSIGN FMSFAA 
$ i Compile and Link SAMP in each Language. 
: ' eeeBAS] (eee 
' 
4 VAISCAL BACK aktmegotine VMISROCT: CSYSEXEJBASIC.EXE - 
. IF VAXEMSBAASSTAI NES. ‘’S** THEN GOTO 50$ 
$ Tf +NOTs SSTATUS. THEN COTO 4 VMISKWD: SAMP.BAS 
$ IF .NO STATUS THEN GOTO 40$ 
$ SET ON 
e § TO 50$ 
$ dos: 
$ SET ON 
$ TYPE OB YSSINPUT 


The BASIC version of the VAX-11 FMS Sample Ages Scat ien failed 
to compile. See the VAX-11 FMS Installation Guide and Release 
Notes for error recovery. 


The installation procedure is continuing... 


PPAPMM 


CUTABLE=VMISKWD:SAMP.EXE VMISKWD:SAMP.OBJ,- 
VAISKUD © SMPVECTOR.OBJ,- 
VMI SKWD : SHPMEMRE S .0BJ, - 

apf oh ON 


SsySs Tl 
VMISKWD : FDVSHR/SHAREABL 
$ IF .NOT. SSTATUS THEN GOTO 70$ 
$ SET ON 
g i 
$ 608: 
: VMISCALLBACK PROVIDE_IMAGE VAXFMS$ SAMP.EXE VMISROOT:CSYSHLP.EXAMPLES.FMSJ 
$ 70%: 
$ SET ON 
$ VMISCALLBACK PROVIDE_FILE VAXFMSS SAMP..BAS VMISROOT: CSYSHLP.EXAMPLES.FMS 
$ VMISCALLBACK PROVIDE-FILE VAXFMSS SAMPBAS. COM VMISROOT:CSYSHLP.EXAMPLES.FMS 
; YRISCALLBACK PROVIDE-FILE VAXFMS$ FDVDEF .BAS VMISROOT:CSYSHLP.EXAMPLES.FMS 
; i eeeBL]SSeee 
‘ 
4 VMISCALL SACK FIND_FILE VAXFMS$ VMISROOT:CSYSEXEJBLISS32.EXE - 
S VAXFMSSBLISTAT 
$ IF VAXFMSSBLISTAT .NES. ‘’S'’ THEN GOTO 90$ 
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; oer ie FDVDEF VMISKWD:FDVDEF .REQ 
$ BLISS/OBJ STATUS THEN COTO 6 OBJ VMISKWD:SAMPBLI.BLI 
$ IF .NOT. SSTATUS THEN GOTO 80S 
$ DEASSIGN F 
$ PONE TEXECUTABLE<VMISKUD : SAMPBLI. thee VMISKWD : SAMPBLI .0 
VAISKWD Oey ECTOR.OBJ, VMISKWD:SMPMEMRES.OBJ, Oee$1NPUT/OPTION 
VMISKWD : FDVSHR/SHAREABLE 
$ IF .NOT. SSTATUS THEN GOTO 80$ 
. SET ON 
. VAISCALLBACK PROVIDE_IMAGE VAXFMSS SAMPBLI.EXE VMISROOT:CSYSHLP.EXAMPLES.FMS) 
$! 
$ 80S: 
$ SET ON 
$ TYPE SYSSINPUT 
The BLISS version of the VAX-11 FMS Sample my ple nedy failed 
to compile or Link. See the VAX-11 FMS Installation Guide and 
Release Notes for error recovery. 
The installation procedure is continuing... 
§ ' 
$ 90S: 
$ VMISCALLBACK PROVIDE_FILE VAXFMSS SAMPBLI. mI VMISROOT:CSYSHLP. ere eS 
$ VMISCALLBACK PROVIDE “FILE VAXFMS$ SAMPBLI1.COM VMISROOT:CSYSHLP.EX/MPLES.FMS 
4 YRUESCALLBALK PROVIDE_FILE VAXFMS$ FDVDEF. REQ VMI$ROOT:C(SYSHLP.EXAMPLES.FMSJ 
: i ereeFORTRANete 
i 
4 VAISCALL BACK act eeertntrar VAXFMSS VMISROOT: CSYSEXEJFORTRAN.EXE - 
. IF VAXFMSSFORSTAT NES. AN ge THEN GOTO 110$ 
$ SET NOON 
$ LIBRARY/CREATE/TEXT VMISKWD:SMPFORTXT - 


VMISKWD:SMPACCOM.FOR /MODULE=ACCOUNT_ COMMON,- 
VMISKWD:SMPREGCOM.FOR /MODULE=REGISTER COMMON, - 
ath oy gg aed LF FOR /MODULE=STATUS_AREA,- 

VAISKWD : SMPWORK. — /MODULE=WORK VAREA 


sc” 


FOVDEF VM 
Ke BIDE VORTEC BRE, VMISKWD : SAMPFOR.FOR 
Ss 


PAKAHPHPMOHM 
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FOVDEF 
KEC Uy i bata fo SAMPFOR.EXE VMISKWD:SAMPFOR.OBJ, - 
WD: SMPVECTOR.OBJ, VMISKWD:SMPMEMRES.OBJ, SYSSINPUT/OPTION 
VMI SKWD : FDVSHR/SHAREABLE 
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$ IF .NOT. SSTATUS THEN GOTO 1008 
: one ON 
; val SCALA BACK PROVIDE_IMAGE VAXFMS$ SAMPFOR.EXE VMISROOT:CSYSHLP.EXAMPLES.FMSJ 
$ ! 
$ 100$: 
$$! 
$ SET ON 
$ TYPE SYSSINPUT 
The FORTRAN version of the VAX-11 FMS Sample Application failed 
to compile or Link. See the VAX-11 FMS Installation Guide and 
Release Notes for error recovery. 
The installation procedure is continuing... 
$ ! 
$ 110$: 
$ VMISCALLBACK PROVIDE_FILE VAXFMS$S SAMPFOR.FOR VMISROOT:CSYSHLP.EXAMPLES.FMSJ 
$ VMISCALLBACK PROVIDE_FILE VAXFMSS SAMPFOR. VMISROOT: CSYSHLP.EXAMPLES.FMS) 
$ VMISCALLBACK PROVIDE FILE VAXFMSS FDVDEF.FOR VMISROOT: te tet 
$ VMISCALLBACK PROVIDE_FILE VAXFMSS SMPACCOM.FOR VMISROOT:(CSYSHLP.EXAMPLES.FMSJ 
$ VMISCALLBACK aid Ba VAXFMS$S SMPREGCOM.FOR VMISROOT a Se pet Stet 
$ VMISCALLBACK PROVIDE_FILE VAXFMS$ SMPSTATUS.FOR VMISROOT:CSYSHLP.EXAMPLES.FMS 
: VMISCALLBACK PROVIDE “FILE VAXFMS$S SMPWORK.FOR VMISROOT: CSYSHLP. EXAMPLES. FMSJ 
$ i #eePASCAL eee 
i 
$ VAISCALL BACK of ime ite yA VAXFMS$ VMISROOT: CSYSEXEJPASCAL.EXE - 
. Et. EPROSPRSS TAT NES. ATs THEN GOTO 130% 
$ PASCAL/ENVIRONMENT=VMISKWD:/OBJECT=VMISKWD: VMISKWD:FDVDEF.PAS 
$ IF .NOT. SSTATUS THEN goto ee bin 
$ DEFINE FOVDEF VMISKWD:FDVDEF 
$ PASCAL/NOENVIRONMEN T7OBsECT=URISKWD: :SAMPPAS.OBJ VMISKWD:SAMPPAS.PAS 
$ IF .NOT. SSTATUS THEN GOTO 1 
$ DEASSIGN FDVDEF 
$ DEFINE FDOVDEF VMISKWD:FDVDEF .OBJ 
$ LINK/EXECUTABLE=VMISKWD:SAMPPAS.EXE VMISKWD:SAMPPAS.OBJ, VMISKWD:FDVDEF.OBJ, - 
SKWD:SMPVECTOR.OBJ, VMISKWD:SMPMEMRES.OBJ, SYSSINPUT/OPTION 
VMISKWD: FOV SUR/SHAREABLE 
$ DEASSIGN FDV 
$ IF .NOT. SS TATUS THEN GOTO 120$ 
; oad ON 
7 VAISCALL BACK PROVIDE_IMAGE VAXFMS$ SAMPPAS.EXE VMISROOT:CSYSHLP.EXAMPLES.FMS) 
: GOTO 1 
$ 1208: 
$ SET ON 


$ TYPE SYSSINPUT 
The PASCAL version of the VAX-11 FMS Sample i7es ication failed 


to compile or Link. See the VAX-11 FMS Instal 


ation Guide and 
Release Notes for error recovery. 


The installation procedure is continuing... 


meoneate 
* 


$CALLBACK panics FILE VAXFMSS$ Eopen® ons atentet SYSHLP.EXAMPLES FMS 
SCALLBACK PROVIDE-FILE VAXFMS$ SAMPPAS.COM VMISROOT:(SYSHLP.EXAMPLES.FMS 
SCALLBACK PROVIDE FILE VAXFMSS FDVDEF. BAS. VMI SROOT: SYSHLP.EXAMPLES.FMS 


eeeCeee 
VAISCALLBACK Sie ertts VAXFMS$S VMISROOT: CSYSEXEJVAX11C.EXE - 
if VAXFMSSCSTAT .NES. ‘'S’' THEN GOTO 150$ 
NOON 
INE FOVDEF VMISKWD:FDVDEF .H 
JECT=VMISKWD:SAMPCC.OBJ VMISKWD:SAMPCC.C 
NOT. petals THEN GOTO 140$ 
yb FDVDEF 
/ a rieerres: Phe EXE py bn SAMPCC.OBJ, = 
VMISKWD: SMPVECTO MISKWD: SMPMEMRES .OBJ 
Sootetin CSYSLIBJERTL [B/C IBRARY, SYSS1NPUT/OPTION 
T. SSTATUS THEN GOTO 140$ 


* ” PROVIDE_IMAGE VAXFMSS SAMPCC.EXE VMISROOT:CSYSHLP.EXAMPLES.FMSJ 
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ON 
E SYSSINPUT 


The C version of the VAX-11 FMS Fenpes Application failed 
to compile or Link. See the VAX-11 FMS Installation Guide and 
Release Notes for error recovery. 


The installation procedure is continuing... 
O$: 
ISCALLBACK PROVIDE_FILE VAXFMS$ SAMPCC.C VMISROOT: CSYSHLP.EXAMPLES.FMS) 
MISCALLBACK PROVIDE-FILE VAXFMS$ SAMPCC. Lon VMISROOT: CSYSHLP.EXAMPLES .FMSJ 
ISCALLBACK PROVIDE-FILE VAXFMS$ FDVDEF .H VMISROOT: CSYSHLP.EXAMPLES.FMSJ 


*ee*eC(COBOL eee 


i5 
M 


<—.- 
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aie aceescestne VMISROOT:CSYSEXEJCOBOL.EXE - 
F VAXFMS COBSTAT «NES. ‘'S’’ THEN GOTO 1708 


mmmmnm 


MPC LI 
OBOL /OBJECT=VMISKWD:SAMPCOB.OBJ VMI 
NOT. Fovecee THEN GOTO 1608 


GN 
GN SE SeTAR 
oe 


SMPCOB 
HECUTABLECURISKUD: :SAMPCOB.EXE VMISKWD:SAMPCOB.0O 
np. NRL SKuD:SRPY ECTOR.OBJ, VMISKWD:SMPMEMRES.OBJ, *SYSSINPUT/OPTION 


WD :F AREABLE 
ck SSTATUS THEN GOTO 160$ 
CALLBACK PROVIDE_IMAGE VAXFMSS SAMPCOB.EXt VMISROOT:CSYSHLP.EXAMPLES.FMSJ 


KWD : SAMPCOB.COB 


3 PAHAPAPHAHEFEHEEONO VCH 
mmm 


ae i 4 4 ome A 4 pee <=-- 
_— 


man 


! 
160$: 
SET ON 
TYPE SYSSINPUT 


The COBOL version of the VAX-11 FMS Sample my pet iy failed 
| 
| 


PRHARAGHAS 
3 
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to compile or Link. See the VAX-11 FMS Installation Guide and 
Release Notes for error recovery. 


The installation procedure is continuing... 


$! 
press 
$ VMISCALLBACK PROVIDE_FILE VAXFMS$ SAMPCOB.COB VMISROOT:(SYSHLP.EXAMPLES.FMS) 
$ VMISCALLBACK PROVIDE-FILE VAXFMS$ SAMPCOB.COM VMISROOT:(SYSHLP.EXAMPLES.FMS] 
$ VMISCALLBACK PROVIDE-FILE VAXERSS FDVDEF.LIB VMIS$ROOT:CSYSHLP.EXAMPLES.FMS] 
$ VMISCALLBACK PROVIDE-FILE VAXFMS$ SAMPCOB.LIB VMISROOT:(SYSHLP.EXAMPLES.FMS] 
$ VMISCALLBACK PROVIDE “FILE VAXENSS SMPCOBUAR.LIB VMISROOT:CSYSHLP.EXAMPLES.FMS) 
$! eeePL/leee 
$ ! 
$ VMISCALLBACK FIND FILE VAXFMSS VMISROOT:CSYSEXEJPLIG.EXE - 

VAXFMSSPLISTAT 
$ IF VAXFMSSPLISTAT .NES. "'S'* THEN GOTO 1908 
$ SET NOON 
$ DEFINE FDVDEFCAL VMISKWD: FOVDEFCAL . PLI 
$ PLI/OBJECT=VMISKWD : SAMPPL 1.08) . VMISKWD:SAMPPLI.PLI 
$ IF .NOT. SSTATUS | THEN 6010’ 1 
$ DEASSIGN FDVDEF 
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$ LINK/EXEC Le yy Seas b og SAMPPLI.EXE VMISKWD:SAMPPLI.2BJ 
VMISKWD:SMPVECTOR.OBJ, VMISKWD:SMPMEMRES.OBU, §¥S${NPUT/OPTION 

eu: EDVSHR/SHA REABLE 

ded - SSTATUS THEN GOTO 1808 


ON 

PE SYSSINPUT 
The PL/1 version of the VAX-11 FMS Sample Application failed 
to compile or Link. See the VAX-11 FMS Installation Guide and 
Release Notes for error recovery. 


The installation procedure is continuing... 


PROVID X L.PLI VM 0 : 

SCALLBACK PROVICE mate: VAXFMSS FDVDEFFNC.PLI VMIS$ROO?:CSYSHLP.EXAMPLE 
Move over form Library, data file, SMPVECTOR and SMPMEMRES 
VMISCALLBACK PROVIDE FILE VAXFMS$ SMPVECTOR.OBJ VMISROOT:CSYSHLP.EXAMPLES 
VMISCALLBACK PROVIDE-FILE VAXFMS$ SMPMEMRES.OBJ VMISROOT:CSYSHLP.EXAMPLES 
MISCALLBACK PROVIDE_FILE VAXFMS$ SAMP.FLB VMISROOT: CSYSHLP.EXAMPLES 
MISCALLBACK PROVIDE_FILE VAKFASS SAMP .DAT VMISROOT: CSYSHLP.EXAMPLES 

Tell manager about installing the shared Library 
TYPE SYSS$INPUT 


System Manager: 


PAHAAAAAAPHAPHAGVHHHONN 


sgl completion of this installation, please be sure to edit 
ayptee startup files as described in the VAX=-11 FMS 
Installation Guide and Release Notes. 


$! 

$ IF FSVERIFY() THEN SET NOVERIFY 

: EXIT VMIS_SUCCESS 

: ; End of VAXFMS instellation 
$ IvP: 

$$! 

$ ! Set up error handling 


Soe _82! 
$! 
$ ON WARNING THEN EXIT VMI$_FAILURE 
; ON CONTROL.Y THEN EXIT VMTS_FAILURE 
$ TYPE SYSSINPUT Syn 
Beginning the VAX-11 FMS Installation Verification Procedure. ac 


. 
| 
| 
| 

Make a copy of our master Library | 

FMS/LIBRARY/CREATE/NOLOG IVP.FLB FMSSEXAMPLES:SAMP.FLB 

i Two commands will get an ‘Information’ message. 

TYPE SYSSINPUT 

Please ignore the following informational messages: 

| 


PAAAAAOS 
moe Neesece 


' 
Try extracting a form from a Library 


FMS/LIBRARY/EXTRACT/NOLOG/OUTPUT=ACTDAT IVP/F ORM=ACCOUNT_DATA 
: Now do a directory of the Library 

FMS/DIRECTORY/OUTPUT=NL : IVP.FLB 

Now do a back translate 

FMS/DESCRIPTION/FULL/OUTPUT=CHECK IVP/F ORM=CHECK 

How about a memory resident module of forms? 

FMS/MEMORY _RESIDENT/OUTPUT=MEMORY ACTDAT.FRM 

Did it produce a valid obj file? 


Cece rr rrr cere rrcrcerrercceeccc ccc ce 
te at ne ne at ne fd Pn ms Bnd mt ad BS nt ne nd Dd nd ad ad ht hs Bd Bd pd Bd 
bh be bebe brbehe4ehr4474,b04474,4744747474~454,454- 4747404 


ANAL YZE/OBJECT/OUTPUT=NL : MEMORY 
How about a UAR vector module? 
FMS/VECTOR/OUTPUT=VECTOR ACTDAT.FRM 
Did it produce a valid obj file? 

ANAL YZE/OBJECT/OUTPUT=NL : VECTOR 


Now try the /delete function 
FMS/LIBRARY/DELETE 1VP.FLB/FORM=CHECK 


PAAPAAAPAPAPAPRPFAPRAPASP APARAARAAAAPRHAPKHAPCA 
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| a 


: : Successful test 

$ if FSVERIFY() THEN SET NOVERIFY 

$ EXIT VMIS_SUCCESS 

$ ! End of VAXFMS IVP 

$ End of VAX FMS KITINSTAL.COM 
$ ERR_EXIT: 

$ | 

$$= 

$ IF 

$ Ex 


| 
| 
} 
| 
SSTATUS 
— THEN SET NOVERIFY 


—_——— 


. 5 


B CRASH RECOVERY 


During an installation, VASINSTAL attempts to record enough state 
information so that i can recover from a pyates crash. This 
information is recorded in the file SYSSUPDATE:VMIMARKER.DAT, which is 
gree ed when installation of a product is begun. and deleted when it 
s finished. If, during a system boot TARTUP.COM notices that 
VMIMARKER.DAT exists, it invokes VMSINSTAL with the B option. 
VAS INSTAL snepects the state at the time the crash occurred, and 
recovers according to the step in progress. 


The steps in the following paragraphs refer to the overview in section 


Steps 5, 6, 7 = The user is told to simply start again. 


Step 8 - If the installation was done in safety mode, then 
there are two possibilities. If a library was being updated 
at the time of the crash, the user is told to restore it from 
backup and start again. If something else was happening, the 
user can simply start again. 


If the installation was done in unsafe mode, then the user is 
told to restore the —— disk from backup and start again. 
soere 3° no way to tell what was happening when the system 
crashed. 


o Step 9 - The deferred callbacks are reexecuted. This should 
complete the installation satisfactorily. 


o Steps 10, 11 - The user is told that the installation was 
completed satisfactorily. 


The documentation for VMSINSTAL will have a thorough description of 
crash recovery. 


C PRODUCT-SPECIFIC CALLBACK PROCEDURES 
This a ix describes the conventions for coding a rodye Crepes tt 16 


callback procedure suitable for use with the VMSINSTAL PRODUCT 
callback. The easiest way to present the conventions is with an 
example. Let's say that FOOBAR, the base product for a product group, 
4. to provide a callback procedure. The procedure is named 
FOOBARINS.COM, because the file name should be the product mnemonic 
followed by as much of the word “INSTALL” as possible. This procedure 
is placed in SYSSUPDATE during the installation of FOOBAR. 


When another product wants to perform a caliback to the procedure, it 
includes the following Line in its installation procedure. 


$ VMISCALLBACK PRODUCT FOOBARINS: INCREMENT - 
PRODSINC COUNTFILE.DAT VMISROOT:(CSYSUPD] 2 


and FOOBARINS receives parameters as follows: 


P1 “INCREMENT” 

Pp . ROD oe 

P “COUNTF ILE DAT" 
PG **VMISROOT : SYSUPDJ 
PS 2" 

P6-P8 mr 


The INCREMENT callback is a phony callback for urposes of 
illustration. The parameter order for callbacks should follow the 
those of standard callbacks as Gceorty as possible. The best idea is 
pick a standard callback that is similar to the one you are designing 
and mimic its parameter order. 


The following procedure is a simple example of a product-specific 
callback procedure. 


$! First thing to do is set up a CTRL/Y handler 
$! and an error handler. We don't want to vee 
warnings because they can happen legitimately. 


ON CONTROL_Y THEN VMISCALLBACK CONTROL_Y 
ON ERROR TREN EXIT SSTATUS 


Now we can case on the callback code. 
GOTO ‘P1 
INCREMENT Logical name-type directory integer 


This callback will increment the number stored in 
the file by the specified integer. A new file 

will be created and put back in the original 

place, with the logical name defined to point at it. 


PARAAPAAPAHAAAAHARAGK 
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[$a etiprenaatinaiiinieiadiod 


} 
:.3 | 
| 
$ | 
SINCREMENT: | 
$! Begin by finding the file with the number to be 
$! incremented. If the find fails, then return a 
$! status to inform the caller. 


VMISCALLBACK FIND FILE ‘P2 'P3 ‘P4 S,E 
IF .NOT. SSTATUS THEN EXIT SSTATUS 


Read the record in the file, which contains the number 
to be incremented. 


OPEN/READ VMISPRODUCT FILE. *P2 
| 


READ VMISPRODUCT FILE NUMB 
CLOSE VMISPRODUCT_FILE 


Create a new version of the file in the working directory, 
and put the incremented number in it. 


OPEN/WRITE VMISPRODUCT_FILE VMISKWD:'P3 
WRITE VMISPRODUCT_FILE~'FSINT(FSINT(NUMBER) + FSINT(PS)) 
CLOSE VMISPRODUCT@FILE 


Provide the new file, which will replace the old one. 
Also define the logical name to point at the final file. 


VMISCALLBACK PROVIDE_FILE ‘P2 'P3 'P4 
EXIT SSTATUS 


The following conventions must be followed. 


PAPAAAAAAAFAAAAPHAAPRHAAAAGASGA 


o The procedure must establish a CTRL/Y _ handler that 
(eventually) invokes the CONTROL_Y callback. 


o The procedure must establish an error handler that 
(eventually) exits with the status that caused the handler to 
be invoked. Warnings are not trapped, because they are 
routinely returned from other callbacks. 


vo The first parameter to the procedure is the callback request 
code. Case on this parameter with a GOTO. 


o The code to implement a callback must follow all of the 
conventions outlined elsewhere in this manual. In 
articular, files must be referenced with standard callbacks. 
he FIND FILE callback can be used to determine the existence 
and Location of a file. Logical names and global symbols 
must begin with VMI$, the VMSINSTAL facility name, because | 
the callback procedure is a logical extension of VMSINSTAL. 
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o The return status from a standard callback must be 

wit an if statement to determine success r 
ee | failure is a warning, the error handler will 
nvoked. 


6 3 


checked 


failure. 


not be 


o The callback must return with either VMI$_SUCCESS or 


VAIS FAILURE status, which is propagated Back 
installation procedure. 


to the 


D EXAMPLE FOR DECODING VMISVMS_VERSION 


The following example shows some techniques and methods for decoding 
the VMISVMS_VERSI symbol. While this example only checks for a 
spec itic version, the techniques shown here can be easily adapted to 
check for a range of versions. 


$! uncomment one of the definitions of product$type 
$: uncomment one of the definitions of product$version 


fieldtest (x4.1 for example) 
x4.1 for instance 


$! product$type = "RELEASED ! if ooty on released VMS software 

$! product$version = "04 : VMS 4. 

$! product$type = "UPGRADE" ! if only runs on major vers. fieldtest 

$! product$version = “'x2m9"" ‘ ya tte for instance 

$! product$type = ‘UPDATE’ } f only runs on vms .n maint. update 
! 


product$version = ‘'041"" 


vmi_type = fSelement(0,"',"’, vmi$vms_version) 
vmi_type = fSelement(0," “eval type) 'Ignore the ‘' FT’ if there 
vmi_version = fSelement(1,"',"’,vmi$vms_version) !Get version string 
goto v_‘product$type' 
v_released: 
if product$type .nes. vmi_type then goto vr l20 
Check the major and minor versions separately 
if fSextr(0,2,product$version) .nes. fSextr(0,2,vmi_version) then goto vri20 
if fSextr(2,1,product$version) .les. fSextr(2,1,vmi_version) then goto v_ok 


vmi$callback MESSAGE e version - _ 
“This kit must be instalied on an existing VMS ‘‘product$version system.’ 
exit vmi$_failure 
_update: 
if ipreduct?t yee -nes. vmi_type) then goto vupd20 
! It must the fieldtest of the version we expect 
if fSextr(0,3,product$version) .eqs. fSextr(0,3,vmi_version) then goto v_ok 


‘ymi$callback MESSAGE e fieldtest - 
“This kit can only be installed on field test version ‘''product$version'."' 
exit vmi$_failure 


< 
= 


< 


5 
oe 


FHA PRHFAHGAHA PHGOGKHFHPHEFFAHHLAHECANES 


rade: 
if (product$type .nes. vmi_type) then goto vupg20 
' The Last 3 characters of the version must match. he first letter 


$ 

$ ! of the version on the system must be .ge. the one we expect. 

$ if fSextr(1,3,product$version) .nes. fSextr(1,5,vmi_version) then goto yupeed 

: if fSextr(0,1,product$version) .les. fSextr(0,1,vmi_version) then goto v_o 
vupg20: 

$ vmi$callback MESSAGE e fieldtest - ’ ; : 

“This kit can only be installed on VMS version ‘‘product$version system.’ 

: . exit vmi$_failure 

v_ok: 
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